OpenEdge Development:<br />Progress Dynamics Advanced Development Defining action rules for menu and toolbar items

When you define items for a Progress Dynamics menu or toolbar, you can define a set of action rules that determine when the item (that is, the toolbar button or menu item) is enabled, when it is hidden, and when an alternate image for a toolbar button should be displayed. In fact, this capability is now a standard part of the ADM2 code and determines the behavior of all of the standard Navigation, Commit, and TableIO items in SmartPanels and toolbars. The code to support this replaces the setButtons SmartPanel procedure that has been used in earlier versions of the ADM. Application code can still call setButtons, but it is no longer used as a routine part of the action of enabling and disabling buttons and menu items.

An action rule can be an expression containing a combination of SmartObject property references and function references. The expression controls different actions as follows:

If the expression for the enable rule returns TRUE, then the item is enabled; otherwise it is disabled.

If the expression for the hide rule returns TRUE, then the item is hidden, that is, actually removed from the menu or the toolbar; otherwise it is viewed.

If the expression for the alternate image rule returns TRUE, then the alternate image or Image 2 is displayed for a toolbar button; otherwise the primary image (Image 1) is displayed.

These rules are evaluated whenever the state of the toolbar’s window changes in a way that could require a re-evaluation of the rules, for example, on a page change, when a record is selected or navigated to, or when one of the toolbar buttons or menu items is selected.

You can also programmatically force a re-evaluation of a rule. You get a handle of the toolbar and run the resetTargetActions procedure. You can add the following code in your super procedure of your container:


{getContainerToolbarSource ctHandles} DO i = 1 to NUM-ENTRIES(ctHandles): hHandle = WIDGET-HANDLE(ENTRY,ctHandles) RUN resetTargetActions(’myLink’) IN hHandle. END.

This code will re-evaluate all rules for items having an item link of mylinkTarget.

You define action rules in the Toolbar and Menu Designer as shown in Figure 3–14. If you look at the rules for some existing items, principally in the Navigation, TableIO, and Commit groups, you can see examples of action rules that are defined as a standard part of the framework.

This figure shows the enable rule for the First button or menu item in the Navigation group. What it means is that if the query position is either on the last record or on some record that is not first or last, and the window is in a state where the user is allowed to navigate records, then enable the first item.

QueryPosition is an SDO property that is set whenever a query is opened and whenever the user selects a record or navigates to a new record. Its values are discussed below, along with other useful properties that are frequently used in action rules.

The canNavigate function does a fairly complex analysis of the state of all the objects in the window to determine whether the user should be permitted to move to another record. If an update is pending in a record in the SDO being navigated or in any dependent SDO, for example, then navigation is disabled in the window until the update is completed. This function returns TRUE or FALSE depending on the state of things, and this helps the toolbar determine whether the navigation buttons should be enabled.

Another example of an enable rule is the Save button in the TableIO group, as shown:

NewRecord=add,copy or DataModified

This means that if the NewRecord property indicates that there is either an add or a copy in process, or the Data Modified property indicates that an existing record has been modified, then enable the Save button.

There are no actively used items that have a hide rule, but you can define your own rules to hide unwanted items based on the state of the application at run time.

An example of an alternate image rule is this one for the Comments item, as shown:

hasActiveComments()

This invokes a special function that returns TRUE if the current record has an active Comments record associated with it. If it does, then it displays its alternate image, a Comments button with a check mark on it

, so that the user knows that there are comments to view.

Be cautious about modifying the action rules for standard buttons in the framework, since you change their behavior everywhere they are used. However, there are cases where you might want to modify the action rules for standard buttons. For example, if you want to keep the Save button enabled at all times and in all places in your application when there is anything updateable in the window, rather than having it enabled only when a user has begun to enter changes into a field, you can do this by altering the action rule for the Save button from this:

NewRecord=add, copy or DataModified

ObjectMode=Update,Modify

The ObjectMode property of a viewer can be view if it is read-only, update if it can be enabled by pressing a button, or modify if it is always enabled for input. You can force the Save button to be always enabled by checking for either Update or Modify as the ObjectMode value.